/**
 * 高级示例：展示插件的所有功能特性
 * 
 * 这个文件展示了：
 * 1. 完整的JSDoc注释（包括@returns）
 * 2. 多种参数类型
 * 3. 模块使用示例
 * 4. 复杂的返回类型
 */

/**
 * 计算数组的统计信息
 * @param {Array<number>} numbers - 数字数组
 * @param {boolean} includeStats - 是否包含统计信息
 * @param {Object} options - 计算选项
 * @returns {Object} 包含总和、平均值和统计信息的对象
 */
function calculateArrayStats (numbers, includeStats = true, options = {}) {
  if (!Array.isArray(numbers) || numbers.length === 0)
  {
    return { sum: 0, average: 0, stats: null };
  }

  const sum = numbers.reduce((acc, num) => acc + num, 0);
  const average = sum / numbers.length;

  let stats = null;
  if (includeStats)
  {
    const sorted = [...numbers].sort((a, b) => a - b);
    stats = {
      min: sorted[0],
      max: sorted[sorted.length - 1],
      median: sorted.length % 2 === 0
        ? (sorted[sorted.length / 2 - 1] + sorted[sorted.length / 2]) / 2
        : sorted[Math.floor(sorted.length / 2)],
      count: numbers.length
    };
  }

  return { sum, average, stats, options };
}

/**
 * 异步处理用户数据
 * @param {string} userId - 用户ID
 * @param {Object} userData - 用户数据
 * @returns {Promise<Object>} 处理后的用户数据
 */
async function processUserData (userId, userData) {
  // 模拟异步操作
  await new Promise(resolve => setTimeout(resolve, 100));

  return {
    id: userId,
    processed: true,
    timestamp: new Date(),
    data: {
      ...userData,
      processedAt: new Date().toISOString()
    }
  };
}

/**
 * 使用外部模块的示例（需要安装lodash）
 * @param {Array} items - 待处理的项目
 * @returns {Object} 处理结果
 */
function processWithLodash (items) {
  // 注意：这些函数在实际运行时会使用模拟实现
  const _ = require('lodash');

  const result = {
    mapped: _.map(items, item => item * 2),
    filtered: _.filter(items, item => item > 5),
    reduced: _.reduce(items, (sum, item) => sum + item, 0),
    sorted: _.sortBy(items)
  };

  return result;
}

/**
 * 日期处理函数
 * @param {string|Date} dateInput - 日期输入
 * @param {string} format - 输出格式
 * @returns {string} 格式化后的日期字符串
 */
function formatDate (dateInput, format = 'YYYY-MM-DD') {
  const date = dateInput instanceof Date ? dateInput : new Date(dateInput);

  if (isNaN(date.getTime()))
  {
    throw new Error('无效的日期输入');
  }

  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const day = String(date.getDate()).padStart(2, '0');

  return format
    .replace('YYYY', year)
    .replace('MM', month)
    .replace('DD', day);
}

/**
 * 无参数函数示例
 * @returns {string} 当前时间字符串
 */
function getCurrentTime () {
  return new Date().toLocaleString('zh-CN');
}

/**
 * 可选参数函数
 * @param {string} name - 姓名
 * @param {number} [age] - 年龄（可选）
 * @param {Object} [profile] - 个人资料（可选）
 * @returns {Object} 用户信息对象
 */
function createUserProfile (name, age, profile = {}) {
  return {
    name,
    age: age || '未知',
    profile: {
      createdAt: new Date(),
      ...profile
    }
  };
}

// 测试函数调用
console.log('=== 高级示例测试 ===');

// 测试数组统计
const testNumbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
console.log('数组统计:', calculateArrayStats(testNumbers, true, { precision: 2 }));

// 测试日期格式化
console.log('当前日期:', formatDate(new Date(), 'YYYY年MM月DD日'));

// 测试无参数函数
console.log('当前时间:', getCurrentTime());

// 测试可选参数
console.log('用户资料:', createUserProfile('张三', 25, { city: '北京' }));
console.log('用户资料（部分参数）:', createUserProfile('李四'));

// 测试模块使用（如果可用）
try
{
  console.log('Lodash处理结果:', processWithLodash([1, 3, 5, 7, 9]));
} catch (error)
{
  console.log('Lodash模块不可用，跳过测试');
}
